自动生成接口文档

每当项目即将验收时，都需要写一份详细的接口文档，太累啦！那么，既然已经有了现成的yaml文件，能不能让程序帮我们写呢？答案是可以！

需求：既有yaml文档，生成特定格式的word接口文档。

思路：读取并解析yaml、读取格式文件、将yaml文件内容按格式写到目标文件中。

实现：

• 解析yaml

const PizZip = require("pizzip");
const Docxtemplater = require("docxtemplater");
const yaml = require("yaml");
const path = require("path");
const fs = require("fs");

const exportWordDoc = (demoUrl, outUrl, fileName) => {
  //读
  const file = fs.readFileSync(path.join(__dirname, `./${fileName}`), "utf8");
  const yamlFile = yaml.parse(file);

  const content = fs.readFileSync(
    path.resolve(__dirname, `./${demoUrl}`),
    "binary"
  );
  const zip = new PizZip(content);
  const doc = new Docxtemplater(zip, {
    paragraphLoop: true,
    linebreaks: true,
  });

  //格式
  let result = [];
  for (let path in yamlFile.paths) {
    for (let method in yamlFile.paths[path]) {
      let params = [];
      let out = [];
      if (yamlFile.paths[path][method].requestBody) {
        let name = yamlFile.paths[path][method].requestBody.content[
          "application/json"
        ].schema["$ref"]
          ? yamlFile.paths[path][method].requestBody.content[
              "application/json"
            ].schema["$ref"]
              .split("/")
              .slice(-1)
          : yamlFile.paths[path][method].requestBody.content[
              "application/json"
            ].schema.items["$ref"]
              .split("/")
              .slice(-1);
        params.push({
          name: name,
          type:
            yamlFile.paths[path][method].requestBody.content["application/json"]
              .schema.type ?? "object",
          description: yamlFile.paths[path][method].requestBody.description,
        });
      }
      if (yamlFile.paths[path][method].parameters) {
        for (let item in yamlFile.paths[path][method].parameters) {
          params.push({
            name: yamlFile.paths[path][method].parameters[item].name,
            type:
              yamlFile.paths[path][method].parameters[item].schema.type ?? "",
            description:
              yamlFile.paths[path][method].parameters[item].description ?? "",
          });
        }
      }
      if (yamlFile.paths[path][method].responses[200]?.content) {
        out.push({
          name: yamlFile.paths[path][method].responses[200].content[
            "application/json"
          ].schema["$ref"]
            ? yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema["$ref"]
                .split("/")
                .slice(-1)
            : yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema.format
            ? yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema.format
            : yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema.enum
            ? yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema.enum
            : yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema.name
            ? yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema.name
            : yamlFile.paths[path][method].responses[200].content[
                "application/json"
              ].schema.items["$ref"]
                .split("/")
                .slice(-1),
          type:
            yamlFile.paths[path][method].responses[200].content[
              "application/json"
            ].schema.type ?? "object",
          description:
            yamlFile.paths[path][method].responses[200].content[
              "application/json"
            ].schema.description ?? "",
        });
      }
      if (!params.length) params.push({ name: "", type: "", description: "" });
      if (!out.length) out.push({ name: "", type: "", description: "" });
      result.push({
        index: result.length + 1,
        summary: yamlFile.paths[path][method].summary,
        description: yamlFile.paths[path][method].description,
        path: path,
        method: method,
        params: params,
        out: out,
      });
    }
  }

  //写
  doc.setData({ result });
  doc.render();

  //生成
  const buf = doc.getZip().generate({
    type: "nodebuffer",
    compression: "DEFLATE",
  });
  fs.writeFileSync(path.resolve(__dirname, `./${outUrl}`), buf);
};
exportWordDoc("tsn.docx", "out.docx", "openapi-resource.yaml");

• 在word中填写格式文件

• 运行js文件，生成文档成功！